<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
    <title>SqlMan/Query Concept</title>
    <meta name="description" content="TODO"/>
    <meta name="keywords" content="SqlMan, document, java sql, java jdbc, java orm, jdbc tools, jdbc helper, last one"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" href="https://framework.ajaxjs.com/static/new-ui/css/common.css"/>
    <link rel="stylesheet" href="https://iam.ajaxjs.com/asset/main.css"/>
    <link rel="icon" type="image/png" href="/asset/favicon.png"/>
    <script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
    <script>
            // 获取用户的默认语言
            var userLang = navigator.language || navigator.userLanguage;

            // 检查是否为中文环境（包括简体和繁体）
            if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
                 confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/docs/cn');  // 如果是中文，则弹出提示
            }

            var _hmt = _hmt || [];
            (function() {
              var hm = document.createElement("script");
              hm.src = "https://hm.baidu.com/hm.js?3cb62106ad945fc91efddfe250e1542e";
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(hm, s);
            })();

    </script>
</head>
<body>
<nav>
    <div>
        <div class="links">
            <a href="/">🏠 Home</a>
            |
            ⚙️ Source:
            <a target="_blank" href="https://github.com/lightweight-component/SqlMan">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/SqlMan">Gitcode</a>

            | <a href="/docs/cn">Chinese Version</a>
        </div>
        <h1>
            <img src="/asset/favicon-2x.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;"/> SqlMan
        </h1>
        <h3>Lightweight Data Access Tools -- User Manual
        </h3>
    </div>
</nav>
<div>
    <menu>

        <ul>
            <li class="selected">
                <a href="/docs">Home</a>
            </li>
            <li>
                <a href="/docs/quick-start">Quick Start</a>
            </li>
            <li>
                <a href="/docs/setup">Setup</a>
            </li>
        </ul>
        <h3>Querying the Database</h3>
        <ul>
            <li>
                <a href="/docs/query/query-concept">Query Concept</a>
            </li>
            <li>
                <a href="/docs/query/query-tutorial">Query Tutorial</a>
            </li>
            <li>
                <a href="/docs/query/query-paging">Paging Query</a>
            </li>
        </ul>
        <h3>Writing the data</h3>
        <ul>
            <li>
                <a href="/docs/write/Create-Update-Delete">Create/Update/Delete</a></li>
            <li>
                <a href="/docs/write/batch">Batch Update</a>
            </li>
        </ul>
        <h3>Other Usage</h3>
        <ul>
            <li>
                <a href="/docs/other/sql-xml">SQL in XML</a></li>
            <li>
                <a href="/docs/other/entity">No SQL but Entity</a>
            </li>
        </ul>
        <h3>Misc</h3>
        <ul>
            <li><a href="/docs/common/versions">Release History</a></li>
            <li><a href="/docs/common/contact">Contact</a></li>
        </ul>
    </menu>
    <article class="aj-text">
        <h1>Query Concept</h1>
        <h2>The Concept before start</h2>
        <p>The most straightforward expression that produces results from the DB is a SQL query.To issue a query with a SqlMan Handle, we have to, at least:</p>
        <ul>
            <li>create the query,</li>
            <li>choose how to pass parameters to the query</li>
            <li>choose how to represent the result(s), after the query is executed</li>
        </ul>
        <p>We’ll now look at each of the points above.</p>
        <h2>Create the query</h2>
        <p>We assume that the query is ready to be executed, it's pure SQL statement. Of course, the connection is already established. Then we create a new <code>Sql</code> instance, pass <code>conn</code> to the
            constructor and SQL statement to <code>input()</code> method.</p>
        <pre><code class="language-java">Map&lt;String, Object&gt; result = new Sql(conn).input(&quot;SELECT * FROM shop_address&quot;).query(); // fetch the first one
</code></pre>
        <p>It's important to note that <code>input()</code> method accepts SQL statement and its parameters. The query is not executed until the <code>query()</code> method is called.</p>
        <p>Currently we didn't pass any parameters to the query. We'll talk about how to pass parameters in the next section.</p>
        <p>Here is a question about how to represent the result(s), it can be divded into two parts:</p>
        <ul>
            <li>How many results to fetch? a single one? or a row? or list?</li>
            <li>Which format to represent the result(s)?</li>
        </ul>
        <p>SQlMan abstracts away from the JDBC ResultSet, which has a quite cumbersome API.</p>
        <p>Therefore, it offers several possibilities to access the columns resulting from a query or some other statement that returns a result.</p>
        <p>From the return structure of value(s), we can identify several types:</p>
        <ul>
            <li>A single element, such as a number, a string, a date, etc.</li>
            <li>A single database row, where fields are mapped to the values like key/value pairs, corresponding to <code>Map</code> in Java.</li>
            <li>Multiple rows, which form a two-dimensional structure, corresponding to <code>List&lt;Map&gt;</code> in Java.</li>
        </ul>
        <p>These types correspond to the following methods in SqlMan:</p>
        <ul>
            <li><code>queryOne(Type.class)</code>- Fetches the single value, means the first column of the first row. The return type matches what you pass in</li>
            <li><code>query()</code>- Fetches the first row, returning a <code>Map&lt;String, Object&gt;</code>.</li>
            <li><code>queryList()</code>- Fetch the list of values, means all the columns of all the rows, returning a <code>List&lt;Map&lt;String, Object&gt;&gt;</code>.</li>
        </ul>
        <p>Here are complete examples:</p>
        <pre><code class="language-java">Map&lt;String, Object&gt; result = new Sql(conn).input(&quot;SELECT * FROM shop_address&quot;).query(); // fetch the first one
int result = new Sql(conn).input(&quot;SELECT COUNT(*) AS total FROM shop_address&quot;).queryOne(int.class); // fetch the first one
List&lt;Map&lt;String, Object&gt;&gt; result = new Sql(conn).input(&quot;SELECT * FROM shop_address&quot;).queryList();
</code></pre>
        <h2>Return Format</h2>
        <p>There is the last question: Which format to represent the result(s)?</p>
        <p>---- We’ll now see the simplest ones: Map, we’ll see the more complex ones in the next section.</p>

    </article>
</div>
<footer>
    SqlMan, a part of <a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a> open source. Mail:
    frank@ajaxjs.com, visit <a href="https://blog.csdn.net/zhangxin09" target="_blank">my blog(In Chinese)</a>.
    <br/>
    <br/>
    Copyright © 2025 Frank Cheung. All rights reserved.
    <script>
        var _hmt = _hmt || [];
        (function() {
          var hm = document.createElement("script");
          hm.src = "https://hm.baidu.com/hm.js?3cb62106ad945fc91efddfe250e1542e";
          var s = document.getElementsByTagName("script")[0];
          s.parentNode.insertBefore(hm, s);
        })();

    </script>
</footer>
</body>
</html>